<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>Lesson 4. The Instance Keyword.</title>
<link rel="stylesheet" type="text/css" href="css/site.css" />
<script language="javascript">AC_FL_RunContent = 0;</script>
<script src="js/AC_RunActiveContent.js" language="javascript"></script>
<script src="js/js_functions.js" language="javascript"></script>
</head>

<body>
	
	<table class="header">
		<tr>
			<td width="80">
				<img src="img/logo-small.png" />
			</td>
			<td width="10">
				<table height="40">
					<tr>
						<td class="leftBorderWhite">&nbsp;</td>
					</tr>
				</table>
			</td>	
			<td>
				<table>
					<tr>
						<td><h1>Lesson 4. The Instance Keyword.</h1></td>
					</tr>
				</table>
			</td>
		</tr>
	</table>
	
	<div class="main">
		<h2>In this example you will learn about how to use the <code>instance</code> keyword.</h2>
		<p>The <code>instance</code> keyword is used to retrieve an object that has already been created.</p>
		
		<table class="main">
			<tr>
				<td>The following is an example on how to use the <code>instance</code> keyword.</td>
			</tr>
			<tr>
				<td class="example">
					<h3>FXML:</h3>
					<img src="img/Instance-XML.png" />
					<div class="right"><a href="examples/Instance.xml" target="_blank">source</a></div>
				</td>
			</tr>
			<tr>
				<td class="example">
					<h3>FXML Result:</h3>
					<div id="Instance">
						<script language="javascript">
							if (AC_FL_RunContent == 0) {
								alert("This page requires AC_RunActiveContent.js.");
							} else {
								AC_FL_RunContent(
									'codebase', 'http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=10,0,0,0',
									'src', 'swf/org.fxml.Application',
									'width', '100%',
									'height', '20',
									'quality', 'high',
									'pluginspage', 'http://www.macromedia.com/go/getflashplayer',
									'align', 'middle',
									'play', 'true',
									'loop', 'true',
									'scale', 'noScale',
									'wmode', 'transparent',
									'devicefont', 'false',
									'id', 'Instance',
									'bgcolor', '#c81b1b',
									'name', 'Instance',
									'menu', 'true',
									'allowFullScreen', 'false',
									'allowScriptAccess','sameDomain',
									'movie', 'swf/org.fxml.Application',
									'salign', 'lT',
									'flashVars', 'id=fxm/l&configFile=examples/Instance.xml'
									); //end AC code
							}
						</script>
						</div>
				</td>
			</tr>
		</table>
		
		<p>
			In the example above, we first create a <code>flash.text.TextField</code> object, then target it to set the <code>text</code> property on it, and finally we target it once more to add it to the <code>stage</code>.
		</p>
		<p>
			<b>Note:</b> When we target objects the <code>this</code> keyword is required. This is because all top level objects and top level calls to <code>addChild</code> become properties of the <code>org.fxml.Application</code> object.
			Compare the example above with the ActionScript 3 example below.  
		</p>
		
		<table class="main">
			<tr>
				<td class="example">
					<img src="img/Instance-AS3.png" />
				</td>
			</tr>
			<tr>
				<td>
					The keyword <code>this</code> refers to the <code>org.fxml.Application</code> object.
				</td>
			</tr>
		</table>
		
		<p>
			The <code>instance</code> keyword can be used to target nested objects as well.
		</p>
		
		<table class="main">
			<tr>
				<td>Nested instance example.</td>
			</tr>
			<tr>
				<td class="example">
					<h3>FXML:</h3>
					<img src="img/NestedInstance-XML.png" />
					<div class="right"><a href="examples/NestedInstance.xml" target="_blank">source</a></div>
				</td>
			</tr>
			<tr>
				<td class="example">
					<h3>FXML Result:</h3>
					<div id="NestedInstance">
						<script language="javascript">
							if (AC_FL_RunContent == 0) {
								alert("This page requires AC_RunActiveContent.js.");
							} else {
								AC_FL_RunContent(
									'codebase', 'http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=10,0,0,0',
									'src', 'swf/org.fxml.Application',
									'width', '100%',
									'height', '20',
									'quality', 'high',
									'pluginspage', 'http://www.macromedia.com/go/getflashplayer',
									'align', 'middle',
									'play', 'true',
									'loop', 'true',
									'scale', 'noScale',
									'wmode', 'transparent',
									'devicefont', 'false',
									'id', 'NestedInstance',
									'bgcolor', '#c81b1b',
									'name', 'NestedInstance',
									'menu', 'true',
									'allowFullScreen', 'false',
									'allowScriptAccess','sameDomain',
									'movie', 'swf/org.fxml.Application',
									'salign', 'lT',
									'flashVars', 'id=fxm/l&configFile=examples/NestedInstance.xml'
									); //end AC code
							}
						</script>
						</div>
				</td>
			</tr>
		</table>
		
		<p>
			In the second example, we first create a <code>flash.display.Sprite</code> object, give it a name of "container", then create a <code>flash.text.TextField</code> object give it a name of "textField" and add it as a child to the "container".
			Finally, we target the <code>flash.text.TextField</code> using <i>dot notation</i> (<code>this.container.textField</code>) and set the <code>text</code> property to "Hello World again!". Note that in this example we targeted the elements by their 
			<code>name</code> property. This is only possible for objects that extend <code>flash.display.DisplayObject</code> and have been added to the <code>stage</code>.  All other objects must be referenced by the name of the XML node assigned to them 
			(as in the first example).
		</p>
		
		<p>
			<b>Note:</b> It is important to note that targeting an object is only possible after the entire XML node has finished parsing.
			This can be a hindrance and may cause you to alter the construction of your objects. 
		</p>						 
		<p>
			Consider the Nested instance example above: During the construction of the <code>flash.text.TextField</code> we will not have access to the <code>flash.display.Sprite</code>. This is due to recursion. The parser
			will work from the inside out, which means that as it begins creating objects, it will finish the <code>flash.text.TextField</code> before it finishes the <code>flash.display.Sprite</code>.
			This means that the <code>flash.text.TextField</code> object can not access the <code>flash.display.Sprite</code> (it's <code>parent</code>) until the entire block has finished. This may take some time to get the hang of, 
			however, when in doubt, create your objects independently of each other (as opposed to nested objects) and target them as top level objects to piece together your application.
		</p>
		<br/><br/><br/>
	</div>
</body>
</html>
